home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2002 November / SGI IRIX Base Documentation 2002 November.iso / usr / share / catman / p_man / cat3 / SCSL / dtgsyl.z / dtgsyl
Encoding:
Text File  |  2002-10-03  |  10.0 KB  |  265 lines
  1.  
  2.  
  3.  
  4. DDDDTTTTGGGGSSSSYYYYLLLL((((3333SSSS))))                                                          DDDDTTTTGGGGSSSSYYYYLLLL((((3333SSSS))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      DTGSYL - solve the generalized Sylvester equation
  10.  
  11. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  12.      SUBROUTINE DTGSYL( TRANS, IJOB, M, N, A, LDA, B, LDB, C, LDC, D, LDD, E,
  13.                         LDE, F, LDF, SCALE, DIF, WORK, LWORK, IWORK, INFO )
  14.  
  15.          CHARACTER      TRANS
  16.  
  17.          INTEGER        IJOB, INFO, LDA, LDB, LDC, LDD, LDE, LDF, LWORK, M, N
  18.  
  19.          DOUBLE         PRECISION DIF, SCALE
  20.  
  21.          INTEGER        IWORK( * )
  22.  
  23.          DOUBLE         PRECISION A( LDA, * ), B( LDB, * ), C( LDC, * ), D(
  24.                         LDD, * ), E( LDE, * ), F( LDF, * ), WORK( * )
  25.  
  26. IIIIMMMMPPPPLLLLEEEEMMMMEEEENNNNTTTTAAAATTTTIIIIOOOONNNN
  27.      These routines are part of the SCSL Scientific Library and can be loaded
  28.      using either the -lscs or the -lscs_mp option.  The -lscs_mp option
  29.      directs the linker to use the multi-processor version of the library.
  30.  
  31.      When linking to SCSL with -lscs or -lscs_mp, the default integer size is
  32.      4 bytes (32 bits). Another version of SCSL is available in which integers
  33.      are 8 bytes (64 bits).  This version allows the user access to larger
  34.      memory sizes and helps when porting legacy Cray codes.  It can be loaded
  35.      by using the -lscs_i8 option or the -lscs_i8_mp option. A program may use
  36.      only one of the two versions; 4-byte integer and 8-byte integer library
  37.      calls cannot be mixed.
  38.  
  39. PPPPUUUURRRRPPPPOOOOSSSSEEEE
  40.      DTGSYL solves the generalized Sylvester equation:
  41.                  A * R - L * B = scale * C                 (1)
  42.                  D * R - L * E = scale * F
  43.  
  44.      where R and L are unknown m-by-n matrices, (A, D), (B, E) and (C, F) are
  45.      given matrix pairs of size m-by-m, n-by-n and m-by-n, respectively, with
  46.      real entries. (A, D) and (B, E) must be in generalized (real) Schur
  47.      canonical form, i.e. A, B are upper quasi triangular and D, E are upper
  48.      triangular.
  49.  
  50.      The solution (R, L) overwrites (C, F). 0 <= SCALE <= 1 is an output
  51.      scaling factor chosen to avoid overflow.
  52.  
  53.      In matrix notation (1) is equivalent to solve  Zx = scale b, where Z is
  54.      defined as
  55.  
  56.                 Z = [ kron(In, A)  -kron(B', Im) ]         (2)
  57.                     [ kron(In, D)  -kron(E', Im) ].
  58.  
  59.      Here Ik is the identity matrix of size k and X' is the transpose of X.
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. DDDDTTTTGGGGSSSSYYYYLLLL((((3333SSSS))))                                                          DDDDTTTTGGGGSSSSYYYYLLLL((((3333SSSS))))
  71.  
  72.  
  73.  
  74.      kron(X, Y) is the Kronecker product between the matrices X and Y.
  75.  
  76.      If TRANS = 'T', DTGSYL solves the transposed system Z'*y = scale*b, which
  77.      is equivalent to solve for R and L in
  78.  
  79.                  A' * R  + D' * L   = scale *  C           (3)
  80.                  R  * B' + L  * E'  = scale * (-F)
  81.  
  82.      This case (TRANS = 'T') is used to compute an one-norm-based estimate of
  83.      Dif[(A,D), (B,E)], the separation between the matrix pairs (A,D) and
  84.      (B,E), using DLACON.
  85.  
  86.      If IJOB >= 1, DTGSYL computes a Frobenius norm-based estimate of
  87.      Dif[(A,D),(B,E)]. That is, the reciprocal of a lower bound on the
  88.      reciprocal of the smallest singular value of Z. See [1-2] for more
  89.      information.
  90.  
  91.      This is a level 3 BLAS algorithm.
  92.  
  93.  
  94. AAAARRRRGGGGUUUUMMMMEEEENNNNTTTTSSSS
  95.      TRANS   (input) CHARACTER*1
  96.              = 'N', solve the generalized Sylvester equation (1).  = 'T',
  97.              solve the 'transposed' system (3).
  98.  
  99.      IJOB    (input) INTEGER
  100.              Specifies what kind of functionality to be performed.  =0: solve
  101.              (1) only.
  102.              =1: The functionality of 0 and 3.
  103.              =2: The functionality of 0 and 4.
  104.              =3: Only an estimate of Dif[(A,D), (B,E)] is computed.  (look
  105.              ahead strategy IJOB  = 1 is used).  =4: Only an estimate of
  106.              Dif[(A,D), (B,E)] is computed.  ( DGECON on sub-systems is used
  107.              ).  Not referenced if TRANS = 'T'.
  108.  
  109.      M       (input) INTEGER
  110.              The order of the matrices A and D, and the row dimension of the
  111.              matrices C, F, R and L.
  112.  
  113.      N       (input) INTEGER
  114.              The order of the matrices B and E, and the column dimension of
  115.              the matrices C, F, R and L.
  116.  
  117.      A       (input) DOUBLE PRECISION array, dimension (LDA, M)
  118.              The upper quasi triangular matrix A.
  119.  
  120.      LDA     (input) INTEGER
  121.              The leading dimension of the array A. LDA >= max(1, M).
  122.  
  123.      B       (input) DOUBLE PRECISION array, dimension (LDB, N)
  124.              The upper quasi triangular matrix B.
  125.  
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. DDDDTTTTGGGGSSSSYYYYLLLL((((3333SSSS))))                                                          DDDDTTTTGGGGSSSSYYYYLLLL((((3333SSSS))))
  137.  
  138.  
  139.  
  140.      LDB     (input) INTEGER
  141.              The leading dimension of the array B. LDB >= max(1, N).
  142.  
  143.      C       (input/output) DOUBLE PRECISION array, dimension (LDC, N)
  144.              On entry, C contains the right-hand-side of the first matrix
  145.              equation in (1) or (3).  On exit, if IJOB = 0, 1 or 2, C has been
  146.              overwritten by the solution R. If IJOB = 3 or 4 and TRANS = 'N',
  147.              C holds R, the solution achieved during the computation of the
  148.              Dif-estimate.
  149.  
  150.      LDC     (input) INTEGER
  151.              The leading dimension of the array C. LDC >= max(1, M).
  152.  
  153.      D       (input) DOUBLE PRECISION array, dimension (LDD, M)
  154.              The upper triangular matrix D.
  155.  
  156.      LDD     (input) INTEGER
  157.              The leading dimension of the array D. LDD >= max(1, M).
  158.  
  159.      E       (input) DOUBLE PRECISION array, dimension (LDE, N)
  160.              The upper triangular matrix E.
  161.  
  162.      LDE     (input) INTEGER
  163.              The leading dimension of the array E. LDE >= max(1, N).
  164.  
  165.      F       (input/output) DOUBLE PRECISION array, dimension (LDF, N)
  166.              On entry, F contains the right-hand-side of the second matrix
  167.              equation in (1) or (3).  On exit, if IJOB = 0, 1 or 2, F has been
  168.              overwritten by the solution L. If IJOB = 3 or 4 and TRANS = 'N',
  169.              F holds L, the solution achieved during the computation of the
  170.              Dif-estimate.
  171.  
  172.      LDF     (input) INTEGER
  173.              The leading dimension of the array F. LDF >= max(1, M).
  174.  
  175.      DIF     (output) DOUBLE PRECISION
  176.              On exit DIF is the reciprocal of a lower bound of the reciprocal
  177.              of the Dif-function, i.e. DIF is an upper bound of Dif[(A,D),
  178.              (B,E)] = sigma_min(Z), where Z as in (2).  IF IJOB = 0 or TRANS =
  179.              'T', DIF is not touched.
  180.  
  181.      SCALE   (output) DOUBLE PRECISION
  182.              On exit SCALE is the scaling factor in (1) or (3).  If 0 < SCALE
  183.              < 1, C and F hold the solutions R and L, resp., to a slightly
  184.              perturbed system but the input matrices A, B, D and E have not
  185.              been changed. If SCALE = 0, C and F hold the solutions R and L,
  186.              respectively, to the homogeneous system with C = F = 0. Normally,
  187.              SCALE = 1.
  188.  
  189.      WORK    (workspace/output) DOUBLE PRECISION array, dimension (LWORK)
  190.              If IJOB = 0, WORK is not referenced.  Otherwise, on exit, if INFO
  191.              = 0, WORK(1) returns the optimal LWORK.
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202. DDDDTTTTGGGGSSSSYYYYLLLL((((3333SSSS))))                                                          DDDDTTTTGGGGSSSSYYYYLLLL((((3333SSSS))))
  203.  
  204.  
  205.  
  206.      LWORK   (input) INTEGER
  207.              The dimension of the array WORK. LWORK > = 1.  If IJOB = 1 or 2
  208.              and TRANS = 'N', LWORK >= 2*M*N.
  209.  
  210.              If LWORK = -1, then a workspace query is assumed; the routine
  211.              only calculates the optimal size of the WORK array, returns this
  212.              value as the first entry of the WORK array, and no error message
  213.              related to LWORK is issued by XERBLA.
  214.  
  215.      IWORK   (workspace) INTEGER array, dimension (M+N+6)
  216.  
  217.      INFO    (output) INTEGER
  218.              =0: successful exit
  219.              <0: If INFO = -i, the i-th argument had an illegal value.
  220.              >0: (A, D) and (B, E) have common or close eigenvalues.
  221.  
  222. FFFFUUUURRRRTTTTHHHHEEEERRRR DDDDEEEETTTTAAAAIIIILLLLSSSS
  223.      Based on contributions by
  224.         Bo Kagstrom and Peter Poromaa, Department of Computing Science,
  225.         Umea University, S-901 87 Umea, Sweden.
  226.  
  227.      [1] B. Kagstrom and P. Poromaa, LAPACK-Style Algorithms and Software
  228.          for Solving the Generalized Sylvester Equation and Estimating the
  229.          Separation between Regular Matrix Pairs, Report UMINF - 93.23,
  230.          Department of Computing Science, Umea University, S-901 87 Umea,
  231.          Sweden, December 1993, Revised April 1994, Also as LAPACK Working
  232.          Note 75.  To appear in ACM Trans. on Math. Software, Vol 22,
  233.          No 1, 1996.
  234.  
  235.      [2] B. Kagstrom, A Perturbation Analysis of the Generalized Sylvester
  236.          Equation (AR - LB, DR - LE ) = (C, F), SIAM J. Matrix Anal.
  237.          Appl., 15(4):1045-1060, 1994
  238.  
  239.      [3] B. Kagstrom and L. Westin, Generalized Schur Methods with
  240.          Condition Estimators for Solving the Generalized Sylvester
  241.          Equation, IEEE Transactions on Automatic Control, Vol. 34, No. 7,
  242.          July 1989, pp 745-751.
  243.  
  244.  
  245. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  246.      INTRO_LAPACK(3S), INTRO_SCSL(3S)
  247.  
  248.      This man page is available only online.
  249.  
  250.  
  251.  
  252.  
  253.  
  254.  
  255.  
  256.  
  257.  
  258.  
  259.  
  260.  
  261.                                                                         PPPPaaaaggggeeee 4444
  262.  
  263.  
  264.  
  265.